/*
    * J.A.D.E. Java(TM) Addition to Default Environment.
    * Latest release available at http://jade.dautelle.com/
    * This class is public domain (not copyrighted).
    */
   package ch.twiddlefinger.inet.rewinder.model.parser.conversion;
   
   import java.io.IOException;
   import java.io.InputStream;
  import java.io.OutputStream;
  import java.lang.reflect.Array;
  import java.lang.reflect.Constructor;
  import java.nio.ByteBuffer;
  import java.nio.ByteOrder;
  
  /***
   * <p> This class represents a <code>C/C++ struct</code>; it confers
   *     interoperability between Java classes and C/C++ struct.</p>
   * <p> Unlike <code>C/C++</code>, the storage layout of Java objects is not
   *     determined by the compiler. The layout of objects in memory is deferred
   *     to run time and determined by the interpreter (or just-in-time compiler).
   *     This approach allows for dynamic loading and binding; but also makes
   *     interfacing with <code>C/C++</code> code difficult. Hence, this class for
   *     which the memory layout is defined by the initialization order of the
   *     {@link Struct}'s {@link Member members} and follows the same alignment
   *      rules as <code>C/C++ structs</code>.</p>
   * <p> This class (as well as the {@link Union} sub-class) facilitates:
   *     <ul>
   *     <li> Memory sharing between Java applications and native libraries.</li>
   *     <li> Direct encoding/decoding of streams for which the structure
   *          is defined by legacy C/C++ code.</li>
   *     <li> Serialization/deserialization of Java objects (complete control,
   *          e.g. no class header)</li>
   *     <li> Mapping of Java objects to physical addresses (with JNI).</li>
   *     </ul></p>
   * <p> Because of its one-to-one mapping, it is relatively easy to convert C 
   *     header files (e.g. OpenGL bindings) to Java {@link Struct}/{@link Union}
   *     using simple text macros. Here is an example of C struct:<pre>
   *     struct Date {
   *         unsigned short year;
   *         unsigned char month;
   *         unsigned char day;
   *     };
   *     struct Student {
   *         char        name[64];
   *         struct Date birth;
   *         float       grades[10];
   *         Student*    next;
   *     };</pre>
   *     and here is the Java equivalent using this class:<pre>
   *     public static class Date extends Struct {
   *         public final Unsigned16 year = new Unsigned16();
   *         public final Unsigned8 month = new Unsigned8();
   *         public final Unsigned8 day   = new Unsigned8();
   *     }
   *     public static class Student extends Struct {
   *         public final UTF8String  name   = new UTF8String(64);
   *         public final Date        birth  = (Date) new StructMember(Date.class).get();
   *         public final Float32[]   grades = (Float32[]) new ArrayMember(Float32.class, 10).get();
   *         public final Reference32 next   =  new Reference32(Student.class);
   *     }</pre>
   *     Struct's members are directly accessible:<pre>
   *     Student student = new Student();
   *     student.name.set("John Doe"); // Null terminated (C compatible)
   *     int age = 2003 - student.birth.year.get();
   *     student.grades[2].set(12.5f);
   *     student = (Student) student.next.get();</pre></p>
   * <p> Applications may also work with the raw {@link #byteBuffer() bytes}
   *     directly:<pre>
   *     Struct message = new Message();
   *     SocketChannel socket = SocketChannel.open(address);
   *     // Reads message.
   *     message.byteBuffer().position(0);
   *     socket.read(message.byteBuffer());
   *     // Writes message.
   *     message.byteBuffer().position(0);
   *     socket.write(message.byteBuffer());</pre>
   *     {@link Struct} can be used to read UDP packets directly:<pre>
   *     class MyUdpMessage extends Struct {
   *         ... // UDP message fields.
   *         public MyUdpMessage(byte[] bytes) {
   *             super(ByteBuffer.wrap(bytes));
   *         }
   *     }
   *     public void run() {
   *         byte[] bytes = new byte[1024];
   *         DatagramPacket packet = new DatagramPacket(bytes, bytes.length);
   *         MyUdpMessage message = new MyUdpMessage(bytes);
   *         // packet and message are now different views of the same data. 
   *         while (true) {
   *             _socket.receive(packet);
   *             ... // Process message fields.
   *             packet.setLength(bytes.length); // Reset length to buffer's length.
   *         }
   *     }</pre></p> 
   * <p> It is relatively easy to map instances of this class to any physical
   *     address using
   *     <a href="http://java.sun.com/docs/books/tutorial/native1.1/index.html">
   *     JNI</a>. Here is an example:<pre>
  *     import java.nio.ByteBuffer;
  *     class Clock extends Struct { // Hardware clock mapped to memory.
  *         Unsigned16 seconds  = new Unsigned16(5); // unsigned short seconds:5
  *         Unsigned16 minutes  = new Unsigned16(5); // unsigned short minutes:5
  *         Unsigned16 hours    = new Unsigned16(4); // unsigned short hours:4
  *         Clock() {
  *             super(Clock.nativeBuffer());
  *         }
  *         private static native ByteBuffer nativeBuffer();
  *     }</pre>
  *     Below is the <code>nativeBuffer()</code> implementation
  *     (<code>Clock.c</code>):<pre>
  *     #include &lt;jni.h&gt;
  *     #include "Clock.h" // Generated using javah
  *     JNIEXPORT jobject JNICALL Java_Clock_nativeBuffer (JNIEnv *env, jclass) {
  *         return (*env)->NewDirectByteBuffer(env, clock_address, buffer_size)
  *     }</pre></p>
  * <p> Finally, bit-fields are supported (see <code>Clock</code> example above).
  *     Bit-fields allocation order is defined by the {@link Struct}'s
  *     {@link #byteOrder byte order} (leftmost bit to rightmost bit if
  *     <code>BIG_ENDIAN</code> and rightmost bit to leftmost bit if
  *      <code>LITTLE_ENDIAN</code>).
  *     Bit-fields cannot straddle the storage-unit boundary as defined by their
  *     base type (padding is inserted at the end of the first bit-field
  *     and the second bit-field is put into the next storage unit).</p>
  *
  * <p><i> This class is <b>public domain</b> (not copyrighted).</i></p>
  *
  * @author  <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
  * @version 5.3, December 7, 2003
  */
 public abstract class Struct {
     
     /***
      * Holds the current outer struct during construction process.
      */
     private static final ThreadLocal OUTER = new ThreadLocal();
 
     /***
      * Holds the byte buffer backing the struct.
      */
     private ByteBuffer _byteBuffer;
 
     /***
      * Holds the number of bits currently used (for size calculation).
      */
     private int _bitsUsed;
 
     /***
      * Holds this struct alignment (largest alignment of its members).
      */
     private int _alignment;
 
     /***
      * Holds the current bit index position (during construction).
      */
     private int _bitIndex;
 
     /***
      * Indicates if the index has to be reset for each new field.
      */
     private boolean _resetIndex;
 
     /***
      * Holds the outer struct if any.
      */
     private final Struct _outer;
 
     /***
      * Holds the offset in the outer struct buffer.
      */
     private int _outerOffset;
 
     /***
      * Default constructor. Top-level {@link Struct} created using this
      * constructor are backed by a direct buffer. Inner {@link Struct} are 
      * always backed by the buffer of their outer parent.
      */
     public Struct() {
         this(null);
     }
 
     /***
      * Creates a {@link Struct} backed by the specified {@link ByteBuffer}.
      * This constructor allows for the use of direct buffers mapped
      * to memory. The address of the first field is always at position
      * <code>0</code> in the specified buffer.
      *
      * @param byteBuffer the byte buffer for this {@link Struct}.
      */
     public Struct(ByteBuffer byteBuffer) {
         _resetIndex = (this instanceof Union);
         _byteBuffer = byteBuffer;
         _outer = (Struct)OUTER.get();
     }
 
     /***
      * Returns the size in bytes of this {@link Struct}. The size includes
      * tail padding to satisfy the {@link Struct} alignment requirement
      * (defined by the largest alignment of its {@link Member members}).
      *
      * @return the C/C++ <code>sizeof(this)</code>.
      */
     public final int size() {
         int nbrOfBytes = (_bitsUsed + 7) >> 3;
         return ((nbrOfBytes % _alignment) == 0) ? nbrOfBytes : // Already aligned or packed.
             nbrOfBytes + _alignment - (nbrOfBytes % _alignment); // Tail padding.
     }
 
     /***
      * Returns the {@link ByteBuffer} backing this {@link Struct}.
      *
      * <p> Changes to the buffer's content are visible in the {@link Struct},
      *     and vice versa.</p>
      * <p> The buffer limit is {@link #size()} and its position index is
      *     undefined. Methods modifying the buffer position should either
      *     synchronize on the buffer or work with a duplicate.</p>
      * <p> The buffer of an inner {@link Struct} is a shared subsequence of
      *     the buffer's content of its outer parent.
      * <p> The buffer is direct if, and only if, this {@link Struct}
      *     (or its outer {@link Struct}) is backed by a direct buffer (see
      *     {@link #Struct(ByteBuffer)}).</p>
      * <p> The position index of a {@link Struct.Member} within the buffer is
      *     given by {@link Struct.Member#offset} (the first field member
      *      starting at <code>0</code>).</p>
      *
      * @return the actual byte buffer for this {@link Struct}.
      */
     public final ByteBuffer byteBuffer() {
         return (_byteBuffer != null) ? _byteBuffer : newBuffer();
     }
 
     private synchronized ByteBuffer newBuffer() {
         if (_byteBuffer == null) { // Avoids concurrent allocations.
             int size = size();
             if (_outer == null) { // Allocates a direct buffer.
                 int capacity = isPacked() ? 
                      // Covers misaligned 64 bits access when packed.
                      ((( size & 0x7)==0) ? size : size + 8 - ( size & 0x7)) :    
                      size;
                 _byteBuffer = ByteBuffer.allocateDirect(capacity);
                 _byteBuffer.order(byteOrder());
             } else { // Subsequence of outer buffer.
                 ByteBuffer outerBuffer = _outer.byteBuffer();
                 synchronized (outerBuffer) {
                     outerBuffer.position(_outerOffset);
                     ByteBuffer subBuffer = outerBuffer.slice();
                     // No need to set the limit, field access is controlled.
                     _byteBuffer = subBuffer;
                 }
                 _byteBuffer.order(_outer.byteOrder());
             }
         }
         return _byteBuffer;
     }
 
     /***
      * Copies the content of the specified source {@link Struct} to the
      * specified destination {@link Struct}.
      *
      * @param  src the source {@link Struct}.
      * @param  dest the destination {@link Struct}.
      * @return <code>dest</code>
      * @throws IllegalArgumentException if <code>dest</code> is not an instance
      *         of <code>src.getClass()</code>,
      */
     public static Struct copy(Struct src, Struct dest) {
         if (src.getClass().isInstance(dest)) {
             ByteBuffer srcBuffer = src.byteBuffer();
             ByteBuffer destBuffer = dest.byteBuffer();
             synchronized (srcBuffer) {
                 synchronized (destBuffer) {
                     srcBuffer.position(0);
                     destBuffer.position(0);
                     srcBuffer.put(destBuffer);
                 }
             }
             return dest;
         } else {
             throw new IllegalArgumentException("Instance of " + src.getClass() +
                 " expected, found instance of " + dest.getClass());
         }
     }
 
     /***
      * Indicates if this {@link Struct} is equal to the specified object.
      *
      * @param  that the object to compare for equality.
      * @return <code>true</code> if this struct and the specified object are
      *         both struct of same class with same content;
      *         <code>false</code> otherwise.
      */
     public boolean equals(Object that) {
         if (this.getClass() == that.getClass()) {
             ByteBuffer thisBuffer = this.byteBuffer();
             ByteBuffer thatBuffer = ((Struct)that).byteBuffer();
             synchronized (thisBuffer) {
                 synchronized (thatBuffer) {
                     thisBuffer.position(0);
                     thatBuffer.position(0);
                     return thisBuffer.equals(thatBuffer);
                 }
             }
         } else {
             return false;
         }
     }
 
     /***
      * Returns a hash code value for this {@link Struct}.
      *
      * <p> Note: Because {@link Struct} hash codes are content-dependent,
      *           it is inadvisable to use {@link Struct} as keys in hash maps
      *           or similar data structures unless it is known that their
      *           contents will not change.</p>
      *
      * @return this struct hash code value.
      */
     public final int hashCode() {
         ByteBuffer thisBuffer = this.byteBuffer();
         synchronized (thisBuffer) {
             thisBuffer.position(0);
             return thisBuffer.hashCode();
         }
     }
 
     /***
      * Returns this {@link Struct} address. This method allows for 
      * {@link Struct} to be referenced (e.g. pointer) from other {@link Struct}.
      *
      * @return the struct memory address.
      * @throws UnsupportedOperationException if the struct's buffer is not 
      *         a direct buffer.
      */
     public final long address() {
         ByteBuffer thisBuffer = this.byteBuffer();
         if (thisBuffer instanceof sun.nio.ch.DirectBuffer) {
             return ((sun.nio.ch.DirectBuffer)thisBuffer).address();
         } else {
            throw new UnsupportedOperationException(
                "Operation not supported for " + thisBuffer.getClass());
         }
     }
 
     /***
      * Returns the <code>String</code> representation of this {@link Struct}
      * in the form of its constituing bytes (hexadecimal). For example:<pre>
      *     public static class Student extends Struct {
      *         UTF8String name  = new UTF8String(16);
      *         Unsigned16 year  = new Unsigned16();
      *         Float32    grade = new Float32();
      *     }
      *     Student student = new Student();
      *     student.name.set("John Doe");
      *     student.year.set(2003);
      *     student.grade.set(12.5f);
      *     System.out.println(student);
      *
      *     4a 6f 68 6e 20 44 6f 65 00 00 00 00 00 00 00 00
      *     07 d3 00 00 41 48 00 00</pre>
      *
      * @return a hexadecimal representation of the bytes content for this
      *         {@link Struct}.
      */
     public final String toString() {
         StringBuffer stringBuffer = new StringBuffer(3 * size());
         final int size = size();
         final ByteBuffer buffer = byteBuffer();
         for (int i = 0; i < size; i++) {
             int b = buffer.get(i) & 0xFF;
             if (b < 0x10) {
                 // Ensures 2 digits per byte for alignment purpose.
                 stringBuffer.append('0');
             }
             TypeFormat.format(b, 16, stringBuffer);
             if ((i & 0xF) == 0xF) {
                 // 16 bytes per line.
                 stringBuffer.append('\n');
             } else {
                 stringBuffer.append(' ');
             }
         }
         return stringBuffer.toString();
     }
 
     ///////////////////
     // CONFIGURATION //
     ///////////////////
 
     /***
      * Returns the byte order for this {@link Struct}. The byte order is
      * inherited by inner structs. Sub-classes may change the byte order
      * by overriding this method. For example:<pre>
      * public final class TopStruct {
      *     ... // Members initialization.
      *     public ByteOrder byteOrder() {
      *         // TopStruct and its inner structs use hardware byte order.
      *         return ByteOrder.nativeOrder();
      *    }
      * }}</pre></p></p>
      *
      * @return the byte order when reading/writing multibyte values
      *         (default: network byte order, <code>BIG_ENDIAN</code>).
      */
     public ByteOrder byteOrder() {
         if (_outer != null) {
             return _outer.byteOrder();
         } else {
             return ByteOrder.BIG_ENDIAN;
         }
     }
 
     /***
      * Indicates if this {@link Struct} is packed.
      * By default, {@link Member} of a {@link Struct} are aligned on the
      * boundary corresponding to the member's base type; padding is performed
      * if necessary. This directive is inherited by inner structs.
      * Sub-classes may change the packing directive by overriding this method.
      * For example:<pre>
      * public final class TopStruct {
      *     ... // Members initialization.
      *     public boolean isPacked() {
      *         // TopStruct and its inner structs are packed.
      *         return true;
      *     }
      * }}</pre></p></p>
      *
      * @return <code>true</code> if alignment requirements are ignored.
      *         <code>false</code> otherwise (default).
      */
     public boolean isPacked() {
         if (_outer != null) {
             return _outer.isPacked();
         } else {
             return false;
         }
     }
 
     /////////////
     // MEMBERS //
     /////////////
 
     /***
      * This inner class represents the base class for all {@link Struct}
      * members. It allows applications to define additional member types.
      * For example:<pre>
      *    public class MyStruct extends Struct {
      *        BitSet bits = new BitSet(256);
      *        ...
      *        public BitSet extends Member {
      *            public BitSet(int nbrBits) {
      *                super(1, (nbrBits+7)>>3);
      *            }
      *            public boolean get(int i) { ... }
      *            public void set(int i, boolean value) { ...}
      *        }
      *    }</pre>
      */
     protected abstract class Member { // Package private.
 
         /***
          * Holds the offset of this field in the struct's buffer.
          */
         private int _offset;
 
         /***
          * Default constructor (used internally for inner struct and bit-fields).
          */
         Member() {} // Package private.
 
         /***
          * Base constructor for custom member types.
          *
          * @param  alignment the desired alignment in bytes.
          * @param  size the size of this member in bytes.
          */
         protected Member(int alignment, int size) {
             final int nbrOfBits = size << 3;
             updateIndexes(alignment, nbrOfBits, nbrOfBits);
         }
 
         /***
          * Returns the offset of this {@link Struct.Member} in the
          * {@link Struct}'s {@link Struct#byteBuffer() byte buffer}.
          *
          * @return the offset in bytes.
          */
         public final int offset() {
             return _offset;
         }
 
         /***
          * Updates the {@link Struct}'s indexes and size.
          *
          * @param  alignment  the desired alignment in bytes.
          * @param  nbrOfBits  the size in bits.
          * @param  capacity   the word size maximum capacity in bits
          *                    (equal to nbrOfBits for non-bitfields).
          * @throws IllegalArgumentException if
          *         <code>nbrOfBits &gt; capacity</code>
          */
         void updateIndexes(int alignment, int nbrOfBits, int capacity) { // Package private.
             if (nbrOfBits > capacity) {
                 throw new IllegalArgumentException("nbrOfBits: " + nbrOfBits +
                     " exceeds capacity: " + capacity);
             }
 
             // Resets index if union.
             if (_resetIndex) {
                 _bitIndex = 0;
             }
 
             // Caculates offset based on alignment constraints.
             alignment = isPacked() ? 1 : alignment;
             _offset = (_bitIndex / (alignment << 3)) * alignment;
             int usedBits = _bitIndex - (_offset << 3);
 
             // Checks if bits can be adjacents.
             if ((capacity < usedBits + nbrOfBits) || (nbrOfBits == 0)) {
                 // Padding to next alignment boundary.
                 _offset += alignment;
                 _bitIndex = (_offset << 3) + nbrOfBits;
             } else { // Adjacent bits.
                 _bitIndex += nbrOfBits;
             }
 
             // Updates bits used (for size calculation).
             if (_bitsUsed < _bitIndex) {
                 _bitsUsed = _bitIndex;
             }
 
             // Updates Struct's alignment.
             if (Struct.this._alignment < alignment) {
                 Struct.this._alignment = alignment;
             }
         }
 
         /***
          * Creates a new instance of specified type.
          *
          * @param  classType the class type.
          * @return an object of the specified class type created using its
          *         default constructor.
          * @throws ClassCastException if classType is not derived from
          *         {@link Struct} or from {@link Struct.Member}.
          */
         Object newInstance(Class classType) { // Package private.
             try {
                 if (Member.class.isAssignableFrom(classType)) {
                     // Inner Member class.
                     Constructor[] constructors = classType.getConstructors();
                     for (int i=0; i < constructors.length; i++) {
                         Class[] params= constructors[i].getParameterTypes();
                         if (    (params.length == 1) &&
                                 Struct.class.isAssignableFrom(params[0])  ) {
                             return constructors[i].newInstance(
                                 new Object[] {Struct.this});
                         }
                     }
                     throw new NoSuchMethodError(
                         classType + " has no public default constructor");
                 }
                 // Inner struct.
                 Struct outer = (Struct)OUTER.get();
                 OUTER.set(Struct.this);
                 Struct struct = (Struct)classType.newInstance();
                 OUTER.set(outer);
                 final int bitSize = struct.size() << 3;
                 updateIndexes(struct._alignment, bitSize, bitSize);
                 struct._outerOffset = (_bitIndex - bitSize) >> 3;
                 return struct;
 
                 // Re-exports any exception as error.
             } catch (InstantiationException e1) {
                 throw new InstantiationError(e1.getMessage());
             } catch (IllegalAccessException e2) {
                 throw new IllegalAccessError(e2.getMessage());
             } catch (java.lang.reflect.InvocationTargetException e3) {
                 throw new Error(e3.getMessage());
             }
         }
     }
 
     /***
      * This class represents an inner struct member.
      */
     public final class StructMember extends Member {
 
         /***
          * Holds the inner struct.
          */
         private final Struct _struct;
 
         /***
          * Creates a {@link Struct.StructMember} having an inner struct
          * of specified type.
          *
          * @param  structType the class of the inner struct.
          * @throws ClassCastException if the specified class is not derived from
          *         {@link Struct}.
          */
         public StructMember(Class structType) {
             _struct = (Struct)newInstance(structType);
         }
 
         /***
          * Returns the struct represented by this {@link Struct.StructMember}.
          *
          * @return the inner struct.
          */
         public Struct get() {
             return _struct;
         }
     }
 
     /***
      * This class represents an array member. Array's element can be
      * {@link Struct.Member} or {@link Struct}/{@link Union}. For example the
      *  following C code:<pre>
      *     struct Vertex {
      *         float x;
      *         float y;
      *     };
      *     struct Rectangle {
      *         int    colors[4];
      *         struct Vertex vertices[2][2];
      *         char   text[4][20];
      *     };</pre>
      *     would be represented by:<pre>
      *     public class Vertex extends Struct {
      *         public final Float32 x = new Float32();
      *         public final Float32 y = new Float32();
      *     }
      *     public class Rectangle extends Struct {
      *         public final Signed32[] colors = (Signed32[]) new ArrayMember(Signed32.class, 4).get();
      *         public final Vertex[][] vertices = (Vertex[][]) new ArrayMember(Vertex.class, new int[] {2, 2}).get();
      *         public final UTF8String20[] text = (UTF8String20[]) new ArrayMember(UTF8String20.class, 4).get();
      *         public class UTF8String20 extends UTF8String {
      *             public UTF8String20() { // Default constructor (no argument) to be used.
      *                 super(20); // UTF8String of 20 bytes.
      *             }
      *         }
      *     }</pre>
      *     Arrays elements are directly accessible:<pre>
      *     float x01 = myRectangle.vertices[0][1].x.get();
      *     myRectangle.colors[2].set(0xFF00FF);
      *     myRectangle.text[0].set("Blah, Blah, Blah");</pre>
      */
     public final class ArrayMember extends Member {
 
         /***
          * Holds the array.
          */
         private final Object _array;
 
         /***
          * Creates an {@link Struct.ArrayMember} of specified component type.
          *
          * @param  componentType the component type of the array.
          * @param  length the length of the array.
          * @throws ClassCastException if the componentType is not derived
          *         from {@link Struct.Member} or {@link Struct}.
          */
         public ArrayMember(Class componentType, int length) {
             this(componentType, new int[] {length});
         }
 
         /***
          * Creates an {@link Struct.ArrayMember} of specified component type and
          * dimensions.
          *
          * @param  componentType the component type of the array.
          * @param  dimensions the dimensions of the array.
          * @throws ClassCastException if the componentType is not derived
          *         from {@link Struct.Member} or {@link Struct}.
          */
         public ArrayMember(Class componentType, int[] dimensions) {
             if (_resetIndex) {
                 _bitIndex = 0;
                 _resetIndex = false; // Ensures elements are sequential.
                 _array = newArray(componentType, dimensions);
                 _resetIndex = true;
             } else {
                 _array = newArray(componentType, dimensions);
             }
         }
 
         private Object newArray(Class componentType, int[] dimensions) {
             Object array = Array.newInstance(componentType, dimensions);
             int length = dimensions[0];
             if (dimensions.length == 1) { // Populates with componentType
                 for (int i = 0; i < length; i++) {
                     Object obj = newInstance(componentType);
                     Array.set(array, i, obj);
                 }
             } else { // Populates with sub-arrays (recursive).
                 final int[] innerDim = new int[dimensions.length - 1];
                 for (int i = 1; i < dimensions.length; i++) {
                     innerDim[i - 1] = dimensions[i];
                 }
                 for (int i = 0; i < length; i++) {
                     Array.set(array, i, newArray(componentType, innerDim));
                 }
             }
             return array;
         }
 
         /***
          * Returns the array represented by this {@link Struct.ArrayMember}.
          *
          * @return the array member.
          */
         public Object get() {
             return _array;
         }
     }
 
     ///////////////////////
     // PREDEFINED FIELDS //
     ///////////////////////
 
     /***
      * This class represents a UTF-8 character string, null terminated
      * (for C/C++ compatibility)
      */
     public class UTF8String extends Member {
         private final Utf8StreamWriter _writer;
         private final Utf8StreamReader _reader;
         private final char[] _charBuffer;
 
         public UTF8String(int length) {
             super(1, length);
             final int indexLast = offset() + length;
             _writer = new Utf8StreamWriter(length);
             _writer.setOutputStream(new OutputStream() {
                 public void write(int b) throws IOException {
                     final ByteBuffer buffer = byteBuffer();
                     if (buffer.position() < indexLast) {
                         buffer.put((byte)b);
                     } // else discards.
                 }
             });
             _reader = new Utf8StreamReader(length);
             _reader.setInputStream(new InputStream() {
                 public int read() throws IOException {
                     final ByteBuffer buffer = byteBuffer();
                     if (buffer.position() < indexLast) {
                         byte b = buffer.get();
                         if (b != 0) {
                             return b;
                         }
                     }
                     return -1;
                 }
             });
             _charBuffer = new char[length];
         }
 
         public void set(String string) {
             final ByteBuffer buffer = byteBuffer();
             synchronized (buffer) {
                 try {
                     buffer.position(offset());
                     _writer.write(string);
                     _writer.write(0); // Marks end of string.
                     _writer.flush();
                 } catch (IOException e) {
                     throw new Error(e);
                 }
             }
         }
 
         public String get() {
             final ByteBuffer buffer = byteBuffer();
             synchronized (buffer) {
                 try {
                     buffer.position(offset());
                     int length = _reader.read(_charBuffer);
                     return (length > 0) ? new String(_charBuffer, 0,
                         length) : "";
                 } catch (IOException e) {
                     throw new Error(e);
                 }
             }
         }
     }
 
     /***
      * This class represents a 8 bits boolean with <code>true</code> represented
      * by <code>1</code> and <code>false</code> represented by <code>0</code>.
      */
     public class Bool extends Member {
         private final int _mask;
         private final int _shift;
         public Bool() {
             this(8);
         }
 
         public Bool(int nbrOfBits) {
             updateIndexes(1, nbrOfBits, 8);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 8 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = ((1 << nbrOfBits) - 1) << _shift;
         }
 
         public boolean get() {
             return (byteBuffer().get(offset()) & _mask) != 0;
         }
 
         public void set(boolean value) {
             if (_mask == 0xFF) { // Non bit-field.
                 byteBuffer().put(offset(), (byte) (value ? 1 : 0));
             } else { // Bit-field.
                 int prevCleared = byteBuffer().get(offset()) & (~_mask);
                 if (value) {
                     byteBuffer().put(
                         offset(), (byte) (prevCleared | (1 << _shift)));
                 } else {
                     byteBuffer().put(offset(), (byte) (prevCleared));
                 }
             }
         }
     }
 
     /***
      * This class represents a 8 bits signed integer.
      */
     public class Signed8 extends Member {
         private final int _mask;
         private final int _shift;
         private final int _signShift;
         public Signed8() {
             this(8);
         }
         public Signed8(int nbrOfBits) {
             updateIndexes(1, nbrOfBits, 8);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 8 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = ((1 << nbrOfBits) - 1) << _shift;
             _signShift = 32 - _shift - nbrOfBits;
         }
 
         public byte get() {
             if (_mask == 0xFF) { // Non bit-field.
                 return byteBuffer().get(offset());
             } else { // Bit-field.
                 int value = byteBuffer().get(offset());
                 value &= _mask;
                 value <<= _signShift;
                 value >>= _signShift + _shift; // Keeps sign.
                 return (byte)value;
             }
         }
 
         public void set(byte value) {
             if (_mask == 0xFF) { // Non bit-field.
                 byteBuffer().put(offset(), value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 int orMask = byteBuffer().get(offset()) & (~_mask);
                 byteBuffer().put(offset(), (byte)(orMask | value));
             }
         }
     }
 
     /***
      * This class represents a 8 bits unsigned integer.
      */
     public class Unsigned8 extends Member {
         private final int _shift;
         private final int _mask;
         public Unsigned8() {
             this(8);
         }
 
         public Unsigned8(int nbrOfBits) {
             updateIndexes(1, nbrOfBits, 8);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 8 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = ((1 << nbrOfBits) - 1) << _shift;
         }
 
         public short get() {
             int value = byteBuffer().get(offset());
             return (short)((value & _mask) >>> _shift);
         }
 
         public void set(short value) {
             if (_mask == 0xFF) { // Non bit-field.
                 byteBuffer().put(offset(), (byte)value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 int orMask = byteBuffer().get(offset()) & (~_mask);
                 byteBuffer().put(offset(), (byte)(orMask | value));
             }
         }
     }
 
     /***
      * This class represents a 16 bits signed integer.
      */
     public class Signed16 extends Member {
         private final int _mask;
         private final int _shift;
         private final int _signShift;
         public Signed16() {
             this(16);
         }
 
         public Signed16(int nbrOfBits) {
             updateIndexes(2, nbrOfBits, 16);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 16 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = ((1 << nbrOfBits) - 1) << _shift;
             _signShift = 32 - _shift - nbrOfBits;
         }
 
         public short get() {
             if (_mask == 0xFFFF) { // Non bit-field.
                 return byteBuffer().getShort(offset());
             } else { // Bit-field.
                 int value = byteBuffer().getShort(offset());
                 value &= _mask;
                 value <<= _signShift;
                 value >>= _signShift + _shift; // Keeps sign.
                 return (short)value;
             }
         }
 
         public void set(short value) {
             if (_mask == 0xFFFF) { // Non bit-field.
                 byteBuffer().putShort(offset(), value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 int orMask = byteBuffer().getShort(offset()) & (~_mask);
                 byteBuffer().putShort(offset(), (short)(orMask | value));
             }
         }
     }
 
     /***
      * This class represents a 16 bits unsigned integer.
      */
     public class Unsigned16 extends Member {
         private final int _shift;
         private final int _mask;
         public Unsigned16() {
             this(16);
         }
 
         public Unsigned16(int nbrOfBits) {
             updateIndexes(2, nbrOfBits, 16);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 16 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = ((1 << nbrOfBits) - 1) << _shift;
         }
 
         public int get() {
             int value = byteBuffer().getShort(offset());
             return (value & _mask) >>> _shift;
         }
 
         public void set(int value) {
             if (_mask == 0xFFFF) { // Non bit-field.
                 byteBuffer().putShort(offset(), (short)value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 int orMask = byteBuffer().getShort(offset()) & (~_mask);
                 byteBuffer().putShort(offset(), (short)(orMask | value));
             }
         }
     }
 
     /***
      * This class represents a 32 bits signed integer.
      */
     public class Signed32 extends Member {
         private final int _mask;
         private final int _shift;
         private final int _signShift;
         public Signed32() {
             this(32);
         }
 
         public Signed32(int nbrOfBits) {
             updateIndexes(4, nbrOfBits, 32);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 32 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = (nbrOfBits == 32) ? 0xFFFFFFFF :
                 ((1 << nbrOfBits) - 1) << _shift;
             _signShift = 32 - _shift - nbrOfBits;
         }
 
         public int get() {
             if (_mask == 0xFFFFFFFF) { // Non bit-field.
                 return byteBuffer().getInt(offset());
             } else { // Bit-field.
                 int value = byteBuffer().getInt(offset());
                 value &= _mask;
                 value <<= _signShift;
                 value >>= _signShift + _shift; // Keeps sign.
                 return value;
             }
         }
 
         public void set(int value) {
             if (_mask == 0xFFFFFFFF) { // Non bit-field.
                 byteBuffer().putInt(offset(), value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 int orMask = byteBuffer().getInt(offset()) & (~_mask);
                 byteBuffer().putInt(offset(), orMask | value);
             }
         }
     }
 
     /***
      * This class represents a 32 bits unsigned integer.
      */
     public class Unsigned32 extends Member {
         private final int _shift;
         private final long _mask;
         public Unsigned32() {
             this(32);
         }
 
         public Unsigned32(int nbrOfBits) {
             updateIndexes(4, nbrOfBits, 32);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 32 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = (nbrOfBits == 32) ? 0xFFFFFFFFl :
                 ((1l << nbrOfBits) - 1l) << _shift;
         }
 
         public long get() {
             int value = byteBuffer().getInt(offset());
             return (value & _mask) >>> _shift;
         }
 
         public void set(long value) {
             if (_mask == 0xFFFFFFFF) { // Non bit-field.
                 byteBuffer().putInt(offset(), (int)value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 int orMask = byteBuffer().getInt(offset()) & (~(int)_mask);
                 byteBuffer().putInt(offset(), (int)(orMask | value));
             }
         }
     }
 
     /***
      * This class represents a 64 bits signed integer.
      */
     public class Signed64 extends Member {
         private final long _mask;
         private final int _shift;
         private final int _signShift;
         public Signed64() {
             this(64);
         }
 
         public Signed64(int nbrOfBits) {
             updateIndexes(8, nbrOfBits, 64);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 64 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = (nbrOfBits == 64) ? 0xFFFFFFFFFFFFFFFFl :
                 ((1l << nbrOfBits) - 1l) << _shift;
             _signShift = 64 - _shift - nbrOfBits;
         }
 
         public long get() {
             if (_mask == 0xFFFFFFFFFFFFFFFFl) { // Non bit-field.
                 return byteBuffer().getLong(offset());
             } else { // Bit-field.
                 long value = byteBuffer().getLong(offset());
                 value &= _mask;
                 value <<= _signShift;
                 value >>= _signShift + _shift; // Keeps sign.
                 return value;
             }
         }
 
         public void set(long value) {
             if (_mask == 0xFFFFFFFFFFFFFFFFl) { // Non bit-field.
                 byteBuffer().putLong(offset(), value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 long orMask = byteBuffer().getLong(offset()) & (~_mask);
                 byteBuffer().putLong(offset(), orMask | value);
             }
         }
     }
 
     /***
      * This class represents a 32 bits float (C/C++/Java <code>float</code>).
      */
     public class Float32 extends Member {
         public Float32() {
             super(4, 4);
         }
 
         public void set(float value) {
             byteBuffer().putFloat(offset(), value);
         }
 
         public float get() {
             return byteBuffer().getFloat(offset());
         }
     }
 
     /***
      * This class represents a 64 bits float (C/C++/Java <code>double</code>).
      */
     public class Float64 extends Member {
         public Float64() {
             super(8, 8);
         }
 
         public void set(double value) {
             byteBuffer().putDouble(offset(), value);
         }
 
         public double get() {
             return byteBuffer().getDouble(offset());
         }
     }
 
     /***
      * <p> This class represents a 32 bits reference (C/C++ pointer) to 
      *     a {@link Struct} object (other types may require a {@link Struct}
      *     wrapper).</p>
      * <p> Note: For references which can be externally modified, an application
      *           may want to check the {@link #isUpToDate up-to-date} status of
      *           the reference. For out-of-date references, a new {@link Struct}
      *           can be created at the address specified by {@link #value} 
      *           (using JNI) and then {@link #set set} to the reference.</p>
      */
     public class Reference32 extends Member {
         private final Class _structClass;
         private Struct _struct;
         public Reference32(Class structClass) {
             super(4, 4);
             if (Struct.class.isAssignableFrom(structClass)) {
                 _structClass = structClass;
             } else {
                 throw new IllegalArgumentException(
                      structClass + " is not a Struct/Union");
             }
         }
 
         public void set(Struct struct) {
             if (_structClass.isInstance(struct)) {
                 byteBuffer().putInt(offset(), (int) struct.address());
             } else if (struct == null) {
                 byteBuffer().putInt(offset(), 0);
             } else {
                 throw new IllegalArgumentException(
                     "struct: Is an instance of " + struct.getClass() + 
                     ", instance of " + _structClass + " expected");
             }
             _struct = struct;
         }
         public Struct get() {
             return _struct;
         }
         public int value() {
             return byteBuffer().getInt(offset());
         }
         public boolean isUpToDate() {
             if (_struct != null) {
                 return byteBuffer().getInt(offset()) == (int)_struct.address();
             } else {
                 return byteBuffer().getInt(offset()) == 0;
             }
         }
     }
     
     /***
      * <p> This class represents a 64 bits reference (C/C++ pointer) to 
      *     a {@link Struct} object (other types may require a {@link Struct}
      *     wrapper).</p>
      * <p> Note: For references which can be externally modified, an application
      *           may want to check the {@link #isUpToDate up-to-date} status of
      *           the reference. For out-of-date references, a new {@link Struct}
      *           can be created at the address specified by {@link #value} 
      *           (using JNI) and then {@link #set set} to the reference.</p>
      */
     public class Reference64 extends Member {
         private final Class _structClass;
         private Struct _struct;
         public Reference64(Class structClass) {
             super(8, 8);
             if (Struct.class.isAssignableFrom(structClass)) {
                 _structClass = structClass;
             } else {
                 throw new IllegalArgumentException(
                      structClass + " is not a Struct/Union");
             }
         }
 
         public void set(Struct struct) {
             if (_structClass.isInstance(struct)) {
                 byteBuffer().putLong(offset(), struct.address());
             } else if (struct == null) {
                 byteBuffer().putLong(offset(), 0L);
             } else {
                 throw new IllegalArgumentException(
                     "struct: Is an instance of " + struct.getClass() + 
                     ", instance of " + _structClass + " expected");
             }
             _struct = struct;
         }
         public Struct get() {
             return _struct;
         }
         public long value() {
             return byteBuffer().getLong(offset());
         }
         public boolean isUpToDate() {
             if (_struct != null) {
                 return byteBuffer().getLong(offset()) == _struct.address();
             } else {
                 return byteBuffer().getLong(offset()) == 0L;
             }
         }
     }
 
     /***
      * This class represents a 8 bits {@link Enum}.
      */
     public class Enum8 extends Member {
         private final int _mask;
         private final int _shift;
         private final int _signShift;
         private final Class _enumClass;
         public Enum8(Class enumClass) {
             this(enumClass, 8);
         }
 
         public Enum8(Class enumClass, int nbrOfBits) {
             _enumClass = enumClass;
             updateIndexes(1, nbrOfBits, 8);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 8 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = ((1 << nbrOfBits) - 1) << _shift;
             _signShift = 32 - _shift - nbrOfBits;
         }
 
         public Enum get() {
             if (_mask == 0xFF) { // Non bit-field.
                 return Enum.valueOf(byteBuffer().get(offset()), _enumClass);
             } else { // Bit-field.
                 int value = byteBuffer().get(offset());
                 value &= _mask;
                 value <<= _signShift;
                 value >>= _signShift + _shift; // Keeps sign.
                 return Enum.valueOf(value, _enumClass);
             }
         }
 
         public void set(Enum enum) {
             if (!_enumClass.isInstance(enum)) {
                 throw new IllegalArgumentException(
                     "enum: " + enum + " is not instance of " + _enumClass);
             }
             byte value = enum.byteValue();
             if (_mask == 0xFF) { // Non bit-field.
                 byteBuffer().put(offset(), value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 int orMask = byteBuffer().get(offset()) & (~_mask);
                 byteBuffer().put(offset(), (byte)(orMask | value));
             }
         }
     }
 
     /***
      * This class represents a 16 bits {@link Enum}.
      */
     public class Enum16 extends Member {
         private final int _mask;
         private final int _shift;
         private final int _signShift;
         private final Class _enumClass;
         public Enum16(Class enumClass) {
             this(enumClass, 16);
         }
 
         public Enum16(Class enumClass, int nbrOfBits) {
             _enumClass = enumClass;
             updateIndexes(2, nbrOfBits, 16);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 16 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = ((1 << nbrOfBits) - 1) << _shift;
             _signShift = 32 - _shift - nbrOfBits;
         }
 
         public Enum get() {
             if (_mask == 0xFFFF) { // Non bit-field.
                 return Enum.valueOf(byteBuffer().getShort(offset()), _enumClass);
             } else { // Bit-field.
                 int value = byteBuffer().getShort(offset());
                 value &= _mask;
                 value <<= _signShift;
                 value >>= _signShift + _shift; // Keeps sign.
                 return Enum.valueOf(value, _enumClass); 
             }
         }
 
         public void set(Enum enum) {
             if (!_enumClass.isInstance(enum)) {
                 throw new IllegalArgumentException(
                     "enum: " + enum + " is not instance of " + _enumClass);
             }
             short value = enum.shortValue();
             if (_mask == 0xFFFF) { // Non bit-field.
                 byteBuffer().putShort(offset(), value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 int orMask = byteBuffer().getShort(offset()) & (~_mask);
                 byteBuffer().putShort(offset(), (short)(orMask | value));
             }
         }
     }
 
     /***
      * This class represents a 32 bits {@link Enum}.
      */
     public class Enum32 extends Member {
         private final int _mask;
         private final int _shift;
         private final int _signShift;
         private final Class _enumClass;
         public Enum32(Class enumClass) {
             this(enumClass, 32);
         }
 
         public Enum32(Class enumClass, int nbrOfBits) {
             _enumClass = enumClass;
             updateIndexes(4, nbrOfBits, 32);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 32 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = (nbrOfBits == 32) ? 0xFFFFFFFF :
                 ((1 << nbrOfBits) - 1) << _shift;
             _signShift = 32 - _shift - nbrOfBits;
         }
 
         public Enum get() {
             if (_mask == 0xFFFFFFFF) { // Non bit-field.
                 return Enum.valueOf(byteBuffer().getInt(offset()), _enumClass);
             } else { // Bit-field.
                 int value = byteBuffer().getInt(offset());
                 value &= _mask;
                 value <<= _signShift;
                 value >>= _signShift + _shift; // Keeps sign.
                 return Enum.valueOf(value, _enumClass);
             }
         }
 
         public void set(Enum enum) {
             if (!_enumClass.isInstance(enum)) {
                 throw new IllegalArgumentException(
                     "enum: " + enum + " is not instance of " + _enumClass);
             }
             int value = enum.intValue();
             if (_mask == 0xFFFFFFFF) { // Non bit-field.
                 byteBuffer().putInt(offset(), value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 int orMask = byteBuffer().getInt(offset()) & (~_mask);
                 byteBuffer().putInt(offset(), orMask | value);
             }
         }
     }
     /***
      * This class represents a 64 bits {@link Enum}.
      */
     public class Enum64 extends Member {
         private final long _mask;
         private final int _shift;
         private final int _signShift;
         private final Class _enumClass;
         public Enum64(Class enumClass) {
             this(enumClass, 64);
         }
         public Enum64(Class enumClass, int nbrOfBits) {
             _enumClass = enumClass;
             updateIndexes(8, nbrOfBits, 64);
             final int startBit = offset() << 3;
             _shift = (byteOrder() == ByteOrder.BIG_ENDIAN) ?
                 64 - _bitIndex + startBit : _bitIndex - startBit - nbrOfBits;
             _mask = (nbrOfBits == 64) ? 0xFFFFFFFFFFFFFFFFl :
                 ((1l << nbrOfBits) - 1l) << _shift;
             _signShift = 64 - _shift - nbrOfBits;
         }
 
         public Enum get() {
             if (_mask == 0xFFFFFFFFFFFFFFFFl) { // Non bit-field.
                 return Enum.valueOf(byteBuffer().getLong(offset()), _enumClass);
             } else { // Bit-field.
                 long value = byteBuffer().getLong(offset());
                 value &= _mask;
                 value <<= _signShift;
                 value >>= _signShift + _shift; // Keeps sign.
                 return Enum.valueOf(value, _enumClass);
             }
         }
 
         public void set(Enum enum) {
             if (!_enumClass.isInstance(enum)) {
                 throw new IllegalArgumentException(
                     "enum: " + enum + " is not instance of " + _enumClass);
             }
             long value = enum.longValue();
             if (_mask == 0xFFFFFFFFFFFFFFFFl) { // Non bit-field.
                 byteBuffer().putLong(offset(), value);
             } else { // Bit-field.
                 value <<= _shift;
                 value &= _mask;
                 long orMask = byteBuffer().getLong(offset()) & (~_mask);
                 byteBuffer().putLong(offset(), orMask | value);
             }
         }
     }
 }